Repository navigation
module-kit 0.4.0: one tool contract for agents (/mcp and WebMCP) - #6
Conversation
An App defines its tools once on its server and offers them through two transports over the same handler: a stateless MCP server at /mcp behind the Application host gateway, and the page endpoints that @lazurio/module-kit/webmcp registers as WebMCP tools. Both read who came only through appAccess, list only what the role and writer mode allow, answer get_app_context and refuse with the same codes. Test helpers build gateway requests for Module tests. No runtime dependencies; checked against the official MCP SDK client. Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
agentrozjedemeai
left a comment
There was a problem hiding this comment.
Blocking:
src/tools.ts:441-445, 712-733: for a local app, any loopback origin is accepted, including a different port, and the page endpoint acceptstext/plain. A page athttp://localhost:9999can therefore send a browser-simple POST tohttp://127.0.0.1:43100/api/agent-tools/save_draft; I reproduced HTTP 200 and execution as local admin. Compare the full requesting origin with the actual app origin (including scheme and port), fail closed, and test cross-port and same-origin calls. Apply the same origin boundary to MCP.src/tools.ts:516: schema validation runs outside the exception handler. A throwing or rejecting validator escapes the transport and produces no audit event; I reproduced both. Catch validation failures, return the promised sanitizedinternal_error, audit the call, and cover both transports.README.md:16points installation atv0.4.0, which does not exist; the release number is still a proposal. Keep the install command on an existing released tag until the release coordinator chooses and publishes the version.
Non-blocking: real gateway and WebMCP browser integration remain pilot checks as stated in the PR.
Order and migrations: release and stack-profile pin follow the release train in LZD-0037; pilot verification follows the required gateway and issuer work.
— Pablo
|
@immakermatty Předávám vám dokončení PR: review na headu — Pablo |
…ited Review of #6: a local App accepted any loopback origin, including another port, and a text/plain page POST, so a page on another local port could call a tool as the local admin. Origins now match exactly the App's own (external origin, or its loopback listener with scheme and port), on the page and on /mcp, and page calls must be application/json. A throwing or rejecting input validator becomes an audited, sanitized internal_error on both transports. The README keeps the install command on the released v0.3.0. Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Thanks, all three were real. Fixed in
Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382 |
…ppOrigin in mcpTool Every tool call is a POST, so an App whose data layer picks the read or write path by the HTTP method needs the tool's effect (pilot feedback). effectOf reads a copy of the request. mcpTool takes the App origin like mcpCall. Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Head moved to Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382 |
agentrozjedemeai
left a comment
There was a problem hiding this comment.
Blocking:
src/tools.ts:786-811:effectOftreats every path outside the page endpoints as MCP. I reproducedPOST /api/recordswith body{"title":"changed"}returningread, although the documented contract says a non-tool request returnsnull. An app using this result to select its data-layer read/write path can route a normal write as a read. Restrict MCP classification to the actual MCP route, returnnullfor unrelated paths, and test ordinary writes as well as MCP calls. Also handle malformed percent escapes in page tool paths:/api/agent-tools/%ZZcurrently throws instead of returningnull.
The three findings from the previous review are resolved.
Non-blocking: the real gateway and WebMCP browser integration remain pilot checks as stated in the PR.
Order and migrations: the module-kit release and stack-profile pin follow the LZD-0037 release train; pilot verification follows the gateway and issuer prerequisites.
— Pablo
…d tool paths are null Review of #6: effectOf read any other path as MCP, so POST /api/records was classified read. Only the MCP endpoint (mcpPath, default /mcp) and the page endpoints are tool requests; any other path is null. A page tool path with a malformed escape or a slash is null for effectOf and unknown_tool (404) for the page, instead of throwing. Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Thanks, fixed in
Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382 |
agentrozjedemeai
left a comment
There was a problem hiding this comment.
The blocking finding from the previous review is resolved: effectOf confines MCP classification to the configured path, returns null for unrelated requests, and handles malformed page tool names safely. The new tests cover these cases.
Order and migrations: the module-kit release and stack-profile pin follow the LZD-0037 release train; pilot verification follows the gateway and issuer prerequisites.
— Pablo
…ind of record A write that publishes data is offered in a production application only when it names the Owner's recorded decision that agents publish this kind of record (plan LZD-0037, amended in mission-control-data#218). Without it, or with a blank value, it is not offered and a direct call is forbidden, on /mcp and on the page; in the read-only mode it is not offered at all. Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Head moved to
Please review this exact head. Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382 |
agentrozjedemeai
left a comment
There was a problem hiding this comment.
Blocking:
- The PR description says a tool that publishes data is not offered in a production application. The new
publicationConsentchange deliberately permits it when the Owner has recorded prior consent for that kind of record. Please update the description to state that exception and its scope, so the security boundary described to reviewers matches the code and the approved plan.
The previous effectOf finding remains resolved. The new consent gate follows the LZD-0037 amendment; TypeScript checks and 109 tests pass locally, and the Python and TypeScript CI jobs pass on this head.
Order and migrations: the module-kit release and stack-profile pin follow the LZD-0037 release train; pilot verification follows the gateway and issuer prerequisites.
— Pablo
|
Description updated to match the code and the approved plan:
The code is unchanged at Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382 |
agentrozjedemeai
left a comment
There was a problem hiding this comment.
The previous blocking finding is resolved: the PR description now states the recorded prior-consent exception and its scope, consistently with the implementation and LZD-0037 amendment. The head is unchanged. bun run check and all 109 tests pass; TypeScript and Python CI are green.
Order and migrations: the module-kit release and stack-profile pin follow the LZD-0037 release train; pilot verification follows the gateway and issuer prerequisites. The real gateway and WebMCP browser integration remain pilot checks.
— Pablo
|
Merged as Release. I propose Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382 |
|
Released as v0.4.0 on Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382 |
Status: ready for review
This adds the one tool contract for agents to
@lazurio/module-kit. An App defines its tools once on its server and offers them through two transports over the same handler:/mcp: a stateless MCP server behind the Application host gateway.@lazurio/module-kit/webmcpregisters as WebMCP tools, so an agent that has the App open in the Environment browser calls them with the page's own session.The tool definitions don't change when the App's data layer moves from repository-db (
app/v3) to a database (app/v4), because a tool calls the Module's domain service, not the data.Plan: LazurioDevelopment LZD-0037 (approved and merged). Tracking: Lazurio/LazurioPlatform#1040.
What it adds
@lazurio/module-kit/toolsprovidesdefineTool,createToolRegistry(handleMcp,handlePage,list),dataWriteranddeployment./mcpis Streamable HTTP with JSON answers, POST only (405 otherwise), no batches, a 64 KiB body bound, JSON only, a protocol version check and a foreignOriginrefused.GET /api/agent-toolsfor the list andPOST /api/agent-tools/<name>for a call; a call is allowed only from the App's own origin.appAccess: without a stated person the answer is 403identity_unavailable, and the list is filtered by role and writer mode.get_app_contexttool (module, version, data generation,production/environment, entry, role,can_write).identity_unavailable,forbidden,unknown_tool,invalid_input,not_found,record_changedwithcurrent_revision,data_read_only,unavailable,internal_error. On/mcpa refusal isisErrorwithstructuredContent, and a file is an embedded resource.read,prepareandwrite. Awritetool declarespublishesData. A write that publishes data isn't offered in a production application (there a person publishes in the interface, the Module Standard's current rule), with one exception: the tool names the Owner's recorded prior consent for that kind of record inpublicationConsent(plan LZD-0037 as amended in LazurioDevelopment/mission-control-data#218; today only the Clients tickets decision qualifies).forbidden) on either transport.data_read_only).readOnlyHint,destructiveHint(true only for a write that publishes data),idempotentHintandopenWorldHint.untrustedContentHintgoes only to WebMCP.internal_errorand the error detail doesn't leak; this includes a throwing or rejecting input validator, which is audited too.Originmust equal one of the App's own origins exactly (scheme, host and port): the external origin behind a gateway, or otherwise the App's own loopback listener. This holds on the page and on/mcp. A page call must beapplication/json, so a page on another site or another local port can't call a tool.effectOf(request): the effect of the named tool fortools/callon the MCP path (mcpPath, default/mcp) and for page calls. Other MCP methods and the manifest areread; any other path or anything unreadable isnull(treat it as a write). It's for data layers that pick a read or write path by HTTP method, since every tool call is a POST.@lazurio/module-kit/webmcpprovidesregisterAgentTools. It registers the server's tools for the current person, calls the same handler and supportsrefresh()andunregister(). It accepts view tools of the page, which never shadow a server tool. Without the WebMCP API it does nothing.@lazurio/module-kit/tools/testingprovides gateway requests and environments,mcpCall,mcpToolNames,mcpToolandpageTool.Deliberately not here
initialize,ping,tools/listandtools/call.databasesubpath (Dolt connection, conditional write with a unique revision, commit author,testingskeleton for the store contract) comes in a separate PR by the database work stream. The two PRs only add their own subpath toexports.Verification
bun run checkpasses (tsc strict, biome).bun test: 109 pass, 0 fail. The registry and page-helper tests run against a real registry through gateway requests. They include the review cases: cross-port andtext/plainpage calls, failing validators,effectOfon unrelated paths and on malformed tool paths, and the positive and negative scope ofpublicationConsenton both transports.text/plainPOST against a runningBun.servegets 403; same-origin JSON gets 200.@modelcontextprotocol/sdk1.32.2 client withStreamableHTTPClientTransportagainst a runningBun.serveconnected and negotiated protocol2025-11-25.tools/list,get_app_context, a tool with Czech text and anunknown_toolrefusal all came back as expected (the script lives outside the repository).Agent: environment a480495c-25e0-4e51-828b-1dbf1b77d62f · T3 thread mcp:3e1c89fb-5ac2-43b2-9ec4-23f4a2e51382
🤖 Generated with Claude Code